Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Transform Objects Reference

Functions / Getting and Setting the Clip

GXSetTransformClip

You can use the GXSetTransformClip function to change a transform object's clip property.

void GXSetTransformClip(gxTransform target, gxShape clip);

target

A reference to the transform object whose clip shape you want to change.

clip

A reference to a shape object containing the new clip shape information.

DESCRIPTION

The GXSetTransformClip function copies information from the shape object referenced by the clip parameter into the clip property of the transform object referenced by the target parameter. You can specify nil for the clip parameter, in which case this function sets the clip property of the target transform to a full clip (no transform clipping takes place).

The new clip shape, which you specify using the clip parameter, may be a geometric shape, a bitmap shape, or a glyph shape. It may not be a picture, text, or layout shape.

• If you specify a geometric shape, it must be in primitive form--that is, all the stylistic information about the shape must be incorporated into the shape's geometry--because this function copies only the geometry-related information from the shape you specify. It does not copy the information contained in the shape's style. You can convert a shape to its primitive form using the GXPrimitiveShape function, which is described in Inside Macintosh: QuickDraw GX Graphics. You can also specify an empty or full shape for a clip.
• If you specify a bitmap shape, it must have a pixel size of 1 and its color profile reference must be nil. In the bitmap, pixel values of 0 obscure drawing; pixel values of 1 do not restrict visibility.
• If you specify a glyph shape, this function uses information from the glyph shape's style object as well as its style list to determine the size, form, and position of the glyph outlines; those outlines are then used to clip drawing. The style list cannot have nil entries. A style object referenced by the glyph shape cannot be complex--that is, it cannot have a cap, join, dash, pattern, text face, font variation, tag list, or any of the properties used only by layout shapes.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
transform_is_nil
shape_is_nil
shapeFill_not_allowed	(debugging version)
colorProfile_must_be_nil	(debugging version)
bitmap_pixel_size_must_be_1	(debugging version)
empty_shape_not_allowed	(debugging version)
ignorePlatformShape_not_allowed	(debugging version)
nil_style_in_glyph_not_allowed	(debugging version)
complex_glyph_style_not_allowed	(debugging version)
illegal_type_for_shape	(debugging version)
Warnings
tags_in_shape_ignored	(debugging version)
Notices (debugging version)
clip_already_set

SEE ALSO

For an example of the use of this function, see page 6-23.

For information about the clip property of transform objects, see "Clip" on page 6-7.

For information about primitive shapes, geometric shapes and bitmap shapes, see
Inside Macintosh: QuickDraw GX Graphics. For information about glyph shapes, see Inside Macintosh: QuickDraw GX Typography.

To examine the clip shape of a transform object, use the GXGetTransformClip function, described in the previous section.

If you want to manipulate the clip property of a transform associated with a specific shape, you can use the GXGetShapeClip function, described next, or the GXSetShapeClip function, described on page 6-46.